You can easily render associated annotation data for your thumbnails by simply connecting ThumbnailXpress to an instance of NotateXpress. If an image has annotation data (such as text, lines, shapes, etc.), ThumbnailXpress will call on NotateXpress to include the annotations in the thumbnail rendering.

Connecting ThumbnailXpress to NotateXpress

The first step in rendering annotations in your thumbnails is to connect your instance of ThumbnailXpress to an instance of NotateXpress. You do this by passing the NotateXpress.InstanceHandle property to the ThumbnailXpress.NotateXpressInstance property.

For example, if you had an instance of ThumbnailXpress named thumbnailXpress1 and an instance of NotateXpress named notateXpress1, you would do this:

thumbnailXpress1.NotateXpressInstance = notateXpress1.InstanceHandle

If you don't do anything else, ThumbnailXpress will automatically render internal image annotation data that NotateXpress supports (NotateXpress, Imaging for Windows, and XFDF formats).

If, however, you need to render annotations stored in external files, you'll need to teach ThumbnailXpress how to find the data using annotation search rules.

Annotation Search Rules

Instead of telling ThumbnailXpress where to find annotation data for each individual image it needs to thumbnail, ThumbnailXpress allows you to give it a list of rules that define where it should search for annotation data. This special annotation rules list is modified via calls to the ThumbnailXpress.SetAnnotationSearchOrderSize and ThumbnailXpress.SetAnnotationSearchOrder methods.

As an image is being thumbnailed, ThumbnailXpress will iterate through its rules list to find associated annotation data. The first rule that succeeds will be used as the source of annotation data for that particular image (if no rule succeeds, then ThumbnailXpress concludes that the image does not have associated annotations and renders a thumbnail without any associated annotations). The entire process repeats when ThumbnailXpress moves on to thumbnail the next image--the search for annotations starts over, and the first rule on the list that returns annotation data "wins."

By default, any new instance of ThumbnailXpress will have pre-loaded this list with three rules:

1. If the image being thumbnailed contains internal Imaging for Windows (WANG) annotation data, use that annotation data.
2. If the image being thumbnailed contains internal NotateXpress annotation data, use that annotation data.
3. If the image being thumbnailed contains internal XFDF (PDF) annotation data, use that annotation data.

This allows you to render internal annotations by simply connecting ThumbnailXpress to NotateXpress.

But if you were to set up the rules list manually yourself, here's how you would do it:

'# Set the search order rule list size appropriately
thumbnailXpress1.SetAnnotationSearchOrderSize 3

'# Add the three internal search rules to the list

'For these calls, only the first and second parameters are used,
'which are simply the index in the list and the annotation type.
thumbnailXpress1.SetAnnotationSearchOrder 0, ANNOTATION_TYPE_I4W, "", "", False 'Imaging for Windows (WANG), which is an internal type
thumbnailXpress1.SetAnnotationSearchOrder 1, ANNOTATION_TYPE_INTERNAL_NXP, "", "", False 'Internal NXP
thumbnailXpress1.SetAnnotationSearchOrder 2, ANNOTATION_TYPE_INTERNAL_XFDF, "", "", False 'Internal XFDF

Or, if you know you only internal need annotation data of a particular type (let's say PDF), you could redefine the search rules to only look for this particular type of annotation data:

'# Set the search order rule list size appropriately
thumbnailXpress1.SetAnnotationSearchOrderSize 1

thumbnailXpress1.SetAnnotationSearchOrder 0, ANNOTATION_TYPE_INTERNAL_XFDF, "", "", False 'Internal XFDF

Setting Up ThumbnailXpress to Render Annotations Stored in External Files

Where the annotation search rules really become important is when your image annotation data is stored externally to the image file. In this case, you must provide a custom set of annotation search rules to ThumbnailXpress in order to teach it how to find your external annotation data.

Before explaining how you do this, it's important to understand that ThumbnailXpress does impose a few requirements on your annotation files:

1. An external annotation file must be located in the same directory as its associated image
2. An external annotation filename must be named similarly to its associated image (the extension may be different, or it may contain an additional name prefix or suffix, but nothing more)
3. An external annotation file must contain annotation data of one of the following types:
   • NotateXpress
   • NotateXpress XML
   • XFDF
   • TMS Sequoia

With that in mind, you define annotation search rules by resizing the rules list (with a call to SetAnnotationSearchOrderSize) and then making calls to SetAnnotationSearchOrder. Each call to SetAnnotationSearchOrder defines a particular search rule by specifying the annotation type, whether the annotation file is named with a prefix or suffix, and whether the annotation file does or does not include the extension of its associated image file. You can consult the API documentation for the details, but a few examples should illustrate how this works.

Example 1 - Using external annotation files using a .nxp extension

Imagine you have a variety of JPEG files with associated NotateXpress annotation data stored in a file of the same name except the ".jpg" extension has been replaced with ".nxp", like so:

• Form1.jpg
• Form1.nxp
• Form2.jpg
• Form2.nxp
• Form3.jpg
• Form3.nxp

You can "teach" ThumbnailXpress to use the Form1.nxp annotation data with the Form1.jpg file, the Form2.nxp annotation data with the Form2.jpg file, etc., by setting up the following annotation search rule:

'Expand the current size of the search rules list by 1
Dim currentSize As Long
currentSize = thumbnailXpress1.GetAnnotationSearchOrderSize
thumbnailXpress1.SetAnnotationSearchOrderSize currentSize + 1

'Add an additional search rule for external NXP annotations
'Param 1 (3): Set the last item in the list
'Param 2 (ANNOTATION_TYPE_NXP): Setup the rule to search for external NotateXpress annotations
'Param 3 (""): No prefix is added to the annotation filename
'Param 4 (".nxp): The Annotation filename ends with ".nxp"
'Param 5 (False): But the annotation filename does not include the original ".jpg" extension of the image filename
thumbnailXpress1.SetAnnotationSearchOrder 3, ANNOTATION_TYPE_NXP, "", ".nxp", False

With one line of code, you have "taught" ThumbnailXpress where it should look for external annotation data. As long as the .nxp files are present, they will be used to render the annotations.

Example 2 - Using only external annotations (ignoring internal annotations)

In the example above, we added a rule that allowed ThumbnailXpress to use annotation data stored in external .nxp files.

Now imagine that our directory contains the following files:

• Form1.tiff - an image with internal annotations
• Form1.nxp - a completely different set of annotations in an external file
• Form2.jpg
• Form2.nxp

In this case, we have a TIFF file with its own internal annotations, as well as a similarly-named external annotation file. The question is, which one will ThumbnailXpress use for its annotation data?

Well, since any new instance of ThumbnailXpress will automatically add internal annotation search rules to the search list by default, if we only add an external annotation rule to the list, then we have essentially told ThumbnailXpress: "I'd like you to look for annotations in this external file, but only if you don't find any internal annotations." So, in the example above, when ThumbnailXpress is rendering Form1.tiff, it will find its internal annotation data and use it; the external annotation data in Form1.nxp will not be used.

If what you really want is for ThumbnailXpress to ignore internal annotation data and always use external annotations, you should resize the search rules list and define only the rules you want:

    'Set the search rules list size to the number of rules we want to define
    thumbnailXpress1.SetAnnotationSearchOrderSize totalNumberOfRules
   
    'Add the rules we care about
    thumbnailXpress1.SetAnnotationSearchOrder 3, ANNOTATION_TYPE_NXP, "", ".nxp", False
    ...

Example 3 - A variety of annotations

Imagine you have a variety of image and annotation files, like so:

• building.jpg
• building.jpg.xml - external NotateXpress XML annotations for Form2.jpg
• house.png
• xfdf-house.png - external XFDF annotations for house.png
• logo.gif
• logo.annotations - external NotateXpress annotations for logo.gif
• Form.tiff - an image with internal NXP annotations which we want
• WangAnnotations.tiff - a document with internal Imaging for Windows annotations
• Example.pdf - a document with internal XFDF annotations which we want

And let's also imagine that you do not want internal Imaging for Windows annotations to ever be rendered.

In this case, here is one way you could set up the ThumbnailXpress annotation search rules:

'Set the search rules list size to the number of rules we want to define
thumbnailXpress1.SetAnnotationSearchOrderSize 5

'# Allow internal NXP
'Param 1 (0): Set the first item in the list
'Param 2 (ANNOTATION_TYPE_INTERNAL_NXP): Setup the rule to search for internal NXP annotations
'Params 3-5 are ignored since they are only relevant for external annotations
thumbnailXpress1.SetAnnotationSearchOrder 0, ANNOTATION_TYPE_INTERNAL_NXP, "", "", False

'# Allow internal XFDF
'Param 1 (1): Set the second item in the list
'Param 2 (ANNOTATION_TYPE_INTERNAL_XFDF): Setup the rule to search for internal XFDF annotations
'Params 3-5 are ignored since they are only relevant for external annotations
thumbnailXpress1.SetAnnotationSearchOrder 1, ANNOTATION_TYPE_INTERNAL_XFDF, "", "", False

'# .xml for NXP XML annotation files
'Param 1 (2): Set the third item in the list
'Param 2 (ANNOTATION_TYPE_XML): Setup the rule to search for external NotateXpress XML annotations
'Param 3 (""): No prefix is added to the annotation filename
'Param 4 (".xml"): The Annotation filename ends with ".xml"
'Param 5 (True): And the annotation filename includes the original extension of the image filename
thumbnailXpress1.SetAnnotationSearchOrder 2, ANNOTATION_TYPE_XML, "", ".xml", True

'# "xfdf-" prefix for XFDF annotation files
'Param 1 (3): Set the fourth item in the list
'Param 2 (ANNOTATION_TYPE_XFDF): Setup the rule to search for external XFDF annotations
'Param 3 ("xfdf-"): The annotation filename begins with an "xfdf-" prefix
'Param 4 (""): No suffix is part of the annotation filename
'Param 5 (True): The annotation filename includes the original extension of the image filename
thumbnailXpress1.SetAnnotationSearchOrder 3, ANNOTATION_TYPE_XFDF, "xfdf-", "", True

'# .annotations for NXP annotation files
'Param 1 (4): Set the fifth item in the list
'Param 2 (ANNOTATION_TYPE_NXP): Setup the rule to search for external NotateXpress annotations
'Param 3 (""): No prefix is added to the annotation filename
'Param 4 (".annotations"): The Annotation filename ends with ".annotations"
'Param 5 (False): The annotation filename does not include the original extension of the image filename
thumbnailXpress1.SetAnnotationSearchOrder 4, ANNOTATION_TYPE_NXP, "", ".annotations", False

This effectively amounts to saying to ThumbnailXpress:

• Don't use your default search rules which include all internal annotation types
• Use these instead:
  1. Try to use internal NXP annotations
  2. If you can't do that, try to use internal XFDF annotations
  3. If you can't do that, try to use external NotateXpress XML annotations stored in a file of the same name with an additional ".xml" extension
  4. If you can't do that, try to use external XFDF annotations stored in a file of the same name with an additional "xfdf-" prefix
  5. If you can't do that, try to use external NotateXpress annotations stored in a file of the same name but whose extension has been changed to ".annotations"

Summary

If you only need ThumbnailXpress to render annotation data embedded in the image file itself, you simply need to connect your instance of ThumbnailXpress to an instance of NotateXpress. But if you want more control over where ThumbnailXpress should look to find associated annotation data for an image (particularly if you are using external annotation data), you'll need to "teach" ThumbnailXpress where it should search for associated annotation data by customizing the annotation search rules.

©2019. Accusoft Corporation. All Rights Reserved.